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13. Stack Groups 



A slack group (usually abbreviated l SG") is a type of I. isp object useful for implementation of 
certain advanced control structures such as coroutines and generators. Processes, which arc a kind 
of coroutine, arc built on top of slack groups (sec chapter 29, page 682). A stack group 
represents a computation and its internal state, including the Lisp stack. 

At any time, the computation being performed by the I. isp Machine is associated with one 
stack group, called the current or running stack group. The operation of making some stack 
group be the current stack group is called a resumption or a stack group switch; the previously 
running stack group is said to have resumed the new stack group. The resume operation has two 
parts: first, the slate of the running compulation is saved away inside the current slack group, 
and secondly the state saved in the new stack group is restored, and the new slack group is made 
current. Then the computation of the new stack group resumes its course. 

The stack group itself holds a great deal of state information. It contains the control stack, or 
regular PDL. The control stack is what you arc shown by the backtracing commands of the error 
handler (Control -B, Meta-B, and Control -Meta-B); it remembers the function which is 
running, its caller, its caller's caller, etc.. and the point of execution of each function (the return 
address of each function). A stack group also contains the dynamic environment stack, or special 
PDL. The name "stack group' derives from the existence of these two stacks. Finally, the stack 
group contains various internal state information (contents of machine registers and so on). 

When the stack group is running, the special PDL contains all the dynamic bindings that are 
shadowed by other bindings in this stack group; bindings that are current reside in the symbols' 
value cells. When the stack group is not running, all of the dynamic bindings it has made reside 
in its special PDL. Switching to a stack group moves the current bindings from the special PDL 
to die symbol value cells, exchanging them with the global or other shadowed bindings. 
Switching out of a stack group docs the reverse process. Note that unwind -protect handlers are 
not run by a stack-group switch (sec let-globally, page 32). 

Each stack group is a separate environment for purposes of function calling, throwing, 
dynamic variable binding, and condition signalling. All stack groups run in the same address 
space; thus they share the same Lisp data and the same global (not lambda-bound) variables. 

When a new stack group is created, it is empty: it doesn't contain the state of any 
computation, so it can't be resumed. In order to get tilings going, the stack group must be set to 
an initial state. This is done by presetting the stack group. To preset a stack group, you supply 
a function and a set of arguments. The stack group is placed in such a state that when it is first 
resumed it will apply this function to those arguments. The function is called the initial function 
of the stack group. 
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13.1 Resuming of Slack Croups 

The interesting thing that happens to staek groups is that they resume each other. When one 
stack group resumes a second staek group, the current state of Lisp execution is saved away in 
the first stack group and is restored from die second stack group. Resuming is also called 
switching slack groups. 

At any time, there is one stack group associated with the current computation; it is called the 
current stack group. The computations associated with other stack groups have their states saved 
away in memory and arc not computing. So the only stack group that can do an> thing at all, in 
particular resuming other stack groups, is the current one. 

You can look at things from the point of view of one computation. Suppose it is running 
along, and it resumes some stack group. The state of the computation state is saved away into its 
own stack group, and the computation associated with the called stack group starts up. The 
original computation lies dormant in the original stack group, while other computations go around 
resuming each other, until finally the original stack group is resumed by someone. Then the 
computation is restored from the stack group and gets to run again. 

There are several ways that the current stack group can resume other stack groups. This 
section describes all of them. 

Bach stack group records a resumer which is nil or another stack group. Some forms of 
resuming examine and alter the resumer of some stack groups. 

Resuming has another ability: it can transmit a Lisp object from the old stack group to the 
new stack group. Each stack group specifies a value to transmit whenever it resumes another stack 
group; whenever a stack group is resumed, it receives a value. 

In the descriptions below, let c stand for the current stack group, s stand for some other 
stack group, and x stand for any arbitrary Lisp object 

Stack groups can be used as functions. They accept one argument. If c calls 5 as a function 
with one argument x, then s is resumed, and the object transmitted is x. When c is resumed 
(usually— but not necessarily— by s), die object transmitted by that resumption is returned as the 
value of the call to s. This is one of the simple ways to resume a stack group: call it as a 
function. The value you transmit is the argument to the function, and the value you receive is 
the value returned from the function. Furdicrmore, this form of resuming sets s's resumer to be 
c. 

Another way to resume a stack group is to use stack -group- return. Rather than allowing 
you to specify which stack group to resume, this function always resumes the resumer of the 
current stack group. Thus, this is a good way to go back to the stack group which called the 
current one, assuming that this was done through a function call, stack -group -return takes one 
argument which is the object to transmit. It returns when something resumes the current stack 
group, and returns one value, the object that was transmitted by that resumption, stack-group- 
return docs not change the resumer of any stack group. 
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The most fundamental way to do resuming is with stack group-resume, which takes two 

arguments: the stack group, and a value to transmit. It returns when someone resumes the 

current stack group, returning the value that was transmitted by that resumption, and does not 
affect any slack group's rcsumer. 

If the initial function of c attempts to return a value x, the regular kind of I.isp function 
return cannot take place, since the function did not have any caller (it got there when the stack 
group was initialized). So instead of normal function returning, a "stack group return" happens, 
(•'s rcsumer is resumed, and the value transmitted is .v. c is left in a state ("exhausted") from 
which it cannot be resumed again; any attempt to resume it signals an error. Presetting it will 
make it work again. 

Those arc the "voluntary" forms of stack group switch; a resumption happens because the 
computation said it should. There arc also two "involuntary" forms, in which another stack group 
is resumed without the explicit request of the running program. 

If an error occurs, the current stack group resumes the error handler stack group. The value 
transmitted is partially descriptive of the error, and die error handler looks inside the saved state 
of the erring stack group to get the rest of the information. The error handler recovers from die 
error by changing the saved state of die erring stack group and Uien resuming it. 

When certain events occur, typically a 1 -second clock tick, a sequence break occurs. This 

forces the current stack group to resume a special stack group called the scheduler (sec section 

29.1, page 683). The scheduler implements processes by resuming, one after another, the stack 
group of each process tiiat is ready to run. 

current- stack- group- resumer Variable 

Is the rcsumer of the current stack group. 

current- stack-group Variable 

Is die stack group which is currently running. A program can use this variable to get its 
hands on its own stack group. 

13.2 Stack Group States 

A stack group has a state, which controls what it will do when it is resumed. The code 
number for the state is returned by die function sys:sg- current -state. This number is the value 
of one of the following symbols. Only the states actually used by the current system are 
documented here; some other codes arc defined but not used. 

sys:sg - state - active 

The stack group is the current one. 

sys:sg-state-resumable 

The stack group is waiting to be resumed, at which time it will pick up 
its saved machine state and continue doing what it was doing before. 

sys:sg-state-awaiting-return 

The stock group called some other stack group as a function. When it is 
resumed, it will return from that function call. 
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sys:sg - state - awaiting ~ initial call 

The stack group has been preset (see below) but has never been called. 
When it is resumed, it will call its initial function with the preset 
arguments. 

sys.sg -state-exhausted 

The stack group's initial function has returned. It cannot be resumed. 

sys:sg - state - awaiting - error - recovery 

When a stack group gets an error it goes into this state, which prevents 
anything from happening to it until the error handler has looked at it. In 
the meantime it cannot be resumed. 

sys:sg- state -invoke -call -on -return 

When the stack group is resumed, it will call a function. The function 
and arguments arc already set up on the stack. The debugger uses this to 
force the stack group being debugged to do things. 

13.3 Stack Group Functions 

make-stack-group name &optional options 

Creates and returns a new stack group, name may be any symbol or string; it is used in 
the stack group's printed representation, options is a list of alternating keywords and 
values. The options are not too useful; most calls to make-stack-group don't need any 
options at all. The options are: 

:sg-area The area in which to create the stack group structure itself. Defaults to 

the default area (the value of default-cons-area). 

:regular-pdl-area 

The area in which to create the regular PDL. Only certain areas specially 
designated when they were created may be used for regular PDLs, 
because regular PDLs arc cached in a hardware device called the pdl 
buffer. Hie default is sys:pdl-area. 

:special- pdl -area 

The area in which to create the special PDL. Defaults to the default area 
(the value of default -cons -area). 

:regular-pdl-size 

Length of the regular PDL to be created. Defaults to 3000 octal. 

:special- pdl -size 

Length of the special PDL to be created. Defaults to 2000 octal. 

:swap-sv-on -call-out 

:swap-sv-of-sg-that-calls-me 

These flags default to 1. If these are 0, the system does not maintain 
separate binding environments for each stack group. You do not want to 
use this feature. 

:trap -enable This determines what to do if a microcode error occurs. If it is 1 the 
system tries to handle the error; if it is the machine halts. Defaults to 
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1. It is only in the error handler stack group, a trap in which would 
not work anyway. 

:safe If this flag is 1 (the default), a strict call-return discipline among stack- 

groups is enforced. If 0, no restriction on stack-group switching is 
imposed. 

sysrpdl-overflow (error) Condition 

This condition is signaled when there is overflow on cither the regular pdl or the special 
pdl. The :pdl-name operation on the condition instance returns cither :special or 
:regular, to tell handlers which one. 

The :grow-pdl proceed type is provided. It takes no arguments. Proceeding from the 
error automatically makes the affected pdl bigger. 

eh:pdl-grow-rat1o Variable 

This is the factor by which to increase the si/.c of a pdl after an overflow. It is initially 
1.5. 

eh:requ1re-pdl-room regpdJ- space specpdl- space 

Makes the current stack group larger if necessary, to make sure that there are at least 

regpdl- space free words in the regular pdl, and at least specpdl- space free words in the 
special pdl, not counting' the words currently in use. 

stack-group-preset stack- group function &rcst arguments 

This sets up stack-group so that when it is resumed, function will be applied to arguments 
within the stack group. Both stacks arc made empty; all saved suite in the stack group is 
destroyed, stack-group-preset is typically used to initialize a stack group just after it is 
made, but it may be done to any stack group at any time. Doing this to a stack group 
which is not exhausted destroys its present state without properly cleaning up by running 
unwind -protects. 

stack-group-resume s x 

Resumes s, transmitting the value x. No stack group's resumcr is affected. 

si:sg-resumable-p s 

t if s's suite permits it to be resumed. 

sysrwrong-stack-group-state (error) Condition 

This is signaled if, for example, you try to resume a stack group which is in the 
exhausted state. 

stack-group-return x 

Resumes the current suick group's resumcr, transmitting the value x. No stack group's 
resumcr is affected. 
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symeval -1n-stack-group symbol sg &oplional frame as- if current 

l-valuates the variable symbol as a special variable in the binding environment of sg. If 
frame is not nil, it evaluates symbol in the binding environment of execution in that 
frame. (A frame is an index in the stack group's regular pdl). 

Two values arc returned: the symbol's value, and a locative to where the value is stored. 
If as-if current is not nil, the locative points to where the value would be stored if sg were 
running. This may be different from where the value is stored now; for example, the 
current binding in stack group sg is stored in symbol's value cell when sg is running, but 
is probably stored in sg's special pdl when sg is not running, as-if current makes no 
difference if sg actually is the current stack group. 

If symbol's current dynamic binding in the specified stack group and frame is void, this 
signals a sys:unbound -variable error. 

13.4 Analyzing Stack Frames 

A stack frame is represented by an index in the regular pdl array of the stack group. The 
word at this index is the function executing, or to be called, in die frame. The following words 
in the pdl contain the arguments. 

sg-regular-pdl sg 

Returns the regular pdl of sg. This is an array of type art-reg-pdl. Stack frames are 
represented as indices into this array. 

sg-regular-pdl-polnter sg 

Returns the index in sgs regular pdl of the last word pushed. 

sg-spedal-pdl sg 

Returns the special pdl of sg. This is an array of type art -special -pdl, used to hold 
special bindings made by functions executing in that stack group. 

sg-spedal-pdl-po1nter sg 

Returns the index in sgs special pdl of the last word pushed. 

The following functions are used to move from one stack frame to another. 

eh:sg-1nnermost-act1ve sg 

Returns (the regular pdl index of) the innermost frame in sg, the one that would be 
executing if sg were current. If sg is current, the value is the frame of the caller of this 
function. 

eh:sg-next-act1ve sg frame 

Returns the next active frame out from frame in sg. This is the one that called frame. If 
frame is the outermost frame, the value is nil. 
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eh :sg-prev1ous active sg frame 

Returns llie previous active frame in from frame in sg. This is the one called by frame. 
If frame is the currently executing frame, the value is nil. If frame is nil, the value is the 
outermost or initial frame. 

eh:sg-1nnermost-open sg 

Returns the innermost open frame in sg, which may be the same as the innermost active 
one or it may be within that. In other respects, this is like eh:sg-innermost-active. 

eh :sg~ next -open sg frame 

like eh :sg- next -active but includes frames which are open, that is, still accumulating 
arguments prior to calling the function. 

eh:sg-prev1ous-open sg frame 

Like eh:sg -previous-active but includes frames which arc open, that is, still 
accumulating arguments prior to calling the function. 

eh:sg-frame-act1ve-p sg frame 

Returns t if frame is active; that is, if the function has been entered. 

Running interpreted code involves calls to eval, cond, etc. which would not be there in 
compiled code. The following three functions can be used to skip over the stack frames of such 
functions, showing only the frames for the functions the user would know about. 

eh:sg-next-1nterest1ng-act1ve sg frame 

Like eh:sg-next~active but skips over uninteresting frames. 

eh:sg-prev1ous-1nterest1ng-act1ve sg frame 

Like eh :sg- previous -active but skips over uninteresting frames. 

eh:sg-out-to-1nterest1ng-act1ve sg frame 

If frame is interesting, returns frame. Otherwise, it returns the next interesting active 
frame. 

Functions to analyze the data in a particular stack frame: 

sys:rp-funct1on-word regpdl frame 

Returns the function executing in frame, regpdl should be the sg-regular-pdl of the 
stack group. 

eh:sg-frame-number-of-spread-args sg frame 

Returns the number of arguments received by frame, which should be an active frame. 
The rest argument (if any) and arguments received by it, do not count. 

eh:sg-frame-arg-value sg frame n 

Returns the value of argument number n of stack frame frame in sg. An error is signaled 
if n is out of range, if the frame is active. (For an open frame, the number of 
arguments is not yet known, so there is no error check.) 
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'I he second value is the location in which the argument is stored when sg is running. The 
location may not actually be in the stack, if the argument is special. The location may 
then contain other contents when the stack group is not running. 

eh:sg-frame-rest-arg-value sg frame 

Returns the value of the rest argument in frame, or nil if there is none. 

The second value is t if the function called in frame expects an explicitly passed rest 
argument. 

The third value is t if the rest argument was passed explicitly. If this is nil, the rest arg 
is a slack list that overlaps the arguments of stack frame frame. If it was passed 
explicitly, it may still be a stack list, but not in this frame. Sec section 5.9, page 112 for 
more information on stack lists. 

eh :sg-frame-number-of- locals sg frame 

Returns the number of local variables in stack frame frame. 

eh:sg-frame-local-value sg frame n 

Returns the value of local variable number // of stack frame frame in sg. An error is 
signaled if // is out of range. 

The second value is the location in which the local is stored when sg is running. The 
location may not actually be in the stack; if not, it may have other contents when the 
stack group is not running. 

eh :sg-frame- value- value sg frame n &optional create-slot 

Returns the value and location of the «'th multiple value frame has returned. If frame 
has not begun to return values, the first value returned is nil but the location still validly 
shows where value number n will be stored. 

If frame was called with multiple-value-list, it can return any number of values, but 
they do not have cells to receive them until frame returns diem. In this case, a non-nil 
create-slot means that this function should allocate cells as necessary so that a valid 
location can be returned. Otherwise, the location as well as the value is nil. 

eh:sg-frame-value-Hst sg frame &optional new- number- of- values 

Returns three values that describe whether frame's caller wants multiple values, and any 
values frame has returned already. 

The first value is a list in which live the values being, or to be, returned by frame. 

The second value is nil if this frame has not been invoked to return multiple values, a 
number which is the number of values it has been asked for, or a locative, meaning the 
frame was called with multiple-value -list. In the last case, the first value includes only 
the values frame has returned already, and the locative points to a cell that points to the 
cons whose cdr should receive the next link of the list. 
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The third value is how m;my values frame has returned so far. 

If new- number of- values is non-nil, it is used to alter the "number of values already 
returned" as recorded in the stack group. This may alter the length of the list that is the 
first value. The value you get is the altered one, in that case. 

eh :sg-frame~ sped al-pdl- range sg frame 

Returns two values delimiting the range of sg's special pdl that belongs to the specified 
stack frame. The first value is the index of the first special pdl word that belongs to the 
frame, and the second value is the index of the next word that docs not belong to it. 

If the specified frame has no special bindings, both values arc nil. Otherwise, the 
indicated special pdl words describe bindings made on entry to or during execution in this 
frame. The words come in pairs. 

The first word of each pair contains die saved value; the second points to the location 
that was bound. When the stack group is not current, the saved value is the value for 
the binding made in this frame. When the stack group is current, the saved value is the 
shadowed value, and die value for this binding is cither in the cell Uiat was bound, or is 
the saved value of another binding, at a higher index, of the same cell. 

The bit sys:%%specpdl -closure-binding is nonzero in the first word of die pair if the 
binding was made before entry to the function itself. This includes bindings made by 
closures, and by instances (including self). Otherwise, the binding was made by the 
function itself. This includes arguments that arc declared special. 

symeval-in-stack-group can be used to find die value of a special variable at a certain stack 
frame (page 261). 

13.5 Input/Output in Stack Groups 

Because each stack group has its own set of dynamic bindings, a stack group docs not inherit 
its creator's value of "terminal -io* (see page 460), nor its caller's, unless you make special 
provision for this. The *terminal-io* a stack group gets by default is a "background" stream that 
docs not normally expect to be used. If it is used, it turns into a "background window" that will 
request die user's attention. Often Uiis happens when an error invokes the debugger. 

If you write a program diat uses multiple stack groups, and you want them all to do input 
and output to the terminal, you should pass die value of "terminal -io* to the top-level function 
of each stack group as part of the stack-group-preset, and Uiat function should bind the 
variable *terminal-io*. 

Another technique is to use a closure as the top-level function of a stack group. This closure 
can bind "terminal- io* and any other variables that should be shared between the stack group 
and its creator. 
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13.6 An Example of Slack Groups 

The canonical coroutine example is the so-called samefringe problem: Given two trees, 
determine whether they contain the same atoms in the same order, ignoring parenthesis structure. 
A better way of saying this is, given two binary trees built out of conses, determine whether the 
sequence of atoms on the fringes of the trees is the same, ignoring differences in the arrangement 
of the internal skeletons of the two trees, hollowing the usual rule for trees, nil in the cdr of a 
cons is to be ignored. 

One way of solving this problem is to use generator coroutines. Wc make a generator for 
each tree, l-ach time the generator is called it returns the next element of the fringe of its tree. 
After the generator has examined the entire tree, it returns a special "exhausted" flag. The 
generator is most naturally written as a recursive function. The use of coroutines, i.e. stack 
groups, allows the two generators to recursc separately on two different control stacks without 
having to coordinate with each other. 

The program is very simple. Constructing it in the usual bottom-up style, we first write a 
recursive function that takes a tree and stack-group- returns each element of its fringe. The 
stack-group-return is how the generator coroutine delivers its output. We could easily test this 
function by changing stack -group -return to print and trying it on some examples. 

(defun fringe (tree) 

(cond ((atom tree) (stack-group-return tree)) 
( t (fringe (car tree)) 

(if (not (null (cdr tree))) 
(fringe (cdr tree)))))) 

Now we package this function inside another, which takes care of returning the special 
"exhausted" flag. 

(defun fringel (tree exhausted) 
(fringe tree) 
exhausted) 

The samefringe function takes the two trees as arguments and returns t or nil. It creates two 
stack groups to act as the two generator coroutines, presets diem to run die fringel function, 
then goes into a loop comparing die two fringes. The value is nil if a difference is discovered, or 
t if they are still the same when the end is reached. 
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(defun samefringe (treel tree2) 

(let ( ( sgl (make-stack-group "samef ringel" ) ) 
(sg2 (make-stack-group "samef ringe2" ) ) 
(exhausted (neons nil))) 
(stack-group-preset sgl tf'fringel treel exhausted) 
(stack-group-preset sg2 0'fringel tree2 exhausted) 
(do ((vl) (v2)) (nil) 

( setq vl (funcall sgl nil ) 
v2 (funcall sg2 nil)) 
(cond ((neq vl v2) (return nil)) 

((eq vl exhausted) (return t)))))) 

Now wc lest it on a couple of examples: 

(samefringe '(a b c) '(a (b c))) => t 
(samefringe '(a b c) '(a b c d)) => nil 

As stack groups arc large, and slow to create, it is desirable to avoid the overhead of creating 
one each time two fringes arc compared. It can easily be eliminated with a modest amount of 
explicit storage allocation, using the resource facility (see page 124). While we're at it, wc can 
avoid making the exhausted flag fresh each time; its only important property is that it not be an 
atom. 

(defresource samef ringe-coroutine () 

constructor (make-stack-group "for-samef ringe")) 

(defvar exhausted-flag (neons nil)) 

(defun samefringe (treel tree2) 

(using-resource (sgl samef ringe-coroutine) 
(using-resource (sg2 samef ringe-coroutine) 

(stack-group-preset sgl #'fringel treel exhausted-flag) 
(stack-group-preset sg2 #'fringel tree2 exhausted-flag) 
(do ((vl) (v2)) (nil) 

(setq vl (funcall sgl nil) 

v2 (funcall sg2 nil)) 
(cond ((neq vl v2) (return nil)) 

((eq vl exhausted-flag) (return t))))))) 

Now we can compare the fringes of two trees with no allocation of memory whatsoever. 
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